<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>JavaScript Benchmarker</title>
    <link rel="stylesheet" href="benchmark_style.css" type="text/css" />
    <script type="text/javascript" src="benchmark.js"></script>
    <link rel="stylesheet" href="tree.css" type="text/css" />
    <script type="text/javascript" src="prototype.js"></script>
    <script type="text/javascript" src="neodom.js"></script>
    <link type="text/css" rel="stylesheet" href="highlight.css" />
    <script type="text/javascript" src="highlight.js"></script>
    <script type="text/javascript" src="lang_js.js"></script>
    <script type="text/javascript" src="lang_html.js"></script>
    <script type="text/javascript" src="benchmarker.js"></script>
  </head>
  <body>
    <h1>
      <a href="benchmarker.js" name="top">Benchmarker</a>
      <em><a href="benchmark.html">Benchmark.js</a> front-end</em>
    </h1>
    <ul class="toc tree" id="toc">
      <li><a href="#version">Version</a></li>
      <li><a href="#synopsis">Synopsis</a></li>
      <li><a href="#examples">Examples</a></li>
      <li><a href="#description">Description</a></li>
      <li><a href="#options">Options</a>
        <ul>
          <li><a href="#option-summary">summary</a></li>
          <li><a href="#option-description">description</a></li>
          <li><a href="#option-scripts">scripts</a></li>
          <li><a href="#option-css">css</a></li>
          <li><a href="#option-edit">edit</a></li>
          <li><a href="#option-editOptions">editOptions</a></li>
          <li><a href="#option-editHandlers">editHandlers</a></li>
          <li><a href="#option-parallel">parallel</a></li>
          <li class="tree-collapsed"><a href="#option-setup">setup</a>
            <ul>
              <li><a href="#setup-methods">methods</a></li>
              <li><a href="#setup-methodSets">methodSets</a></li>
            </ul>
          </li>
        </ul>
      </li>
      <li><a href="#dependencies">Dependencies</a></li>
      <li><a href="#incompatibilities">Incompatibilities</a></li>
      <li><a href="#bugs">Bugs</a></li>
      <li><a href="#todo">To Do</a></li>
      <li><a href="#see-also">See Also</a></li>
      <li><a href="#credits">Credits</a></li>
      <li><a href="#authors">Authors</a></li>
      <li><a href="#license">License</a></li>
      <li><a href="#disclaimer">Disclaimer</a></li>
    </ul>

    <div class="section">
      <h2><a name="version">Version</a></h2>
      <p id="version-revision"><a href="benchmarker.js">use the source, young padawan!</a></p>
    </div>

    <div class="section">
      <h2><a name="synopsis">Synopsis</a></h2>
<pre><code class="whhtml">
&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"&gt;
&lt;html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"&gt;
  &lt;head&gt;
    &lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8" /&gt;
    &lt;title&gt;Benchmark&lt;/title&gt;
    &lt;script type="text/javascript" src="benchmarker.js"&gt;&lt;/script&gt;
    &lt;script type="text/javascript"&gt;</code></pre><pre><code class="whjs">      new Benchmarker(
        {
          // functions to be benchmarked
          // - will be generated using the "setup" block
        },
        {
          // Benchmark options
          iterations:   -2,
          nATime:       1000,
          cooldown:     50,
          runCaps:      4000,
          responders:   'HTMLish',

          // Benchmarker options
          summary:      'my funky benchmark',
          scripts:      [ 'http://www.example.com/js/test.js',
                         'http://www.example.com/js/test2.js' ],
          css:          [ 'http://www.example.com/css/bm.css' ],
          edit:         true,   // expand benchmark editor mode
          editOptions:  false,  // don't expand benchmark options
          editHandlers: false,  // don't expand benchmark handlers
          parallel:     true,   // run methodSets in parallel
          setup: function() {   // setup code
            methodSets = [
              {
                name: 'ack/nack',
                methods: {
                  ack: function() { return true; },
                  nak: function() { return false; },
                }
              },
              {
                name: 'loops',
                methods: {
                    for_loop: function() { for (var i = 0; i != 10; i++); },
                  while_loop: function() { var i = -1; while (++i != 10); },
                }
              }
            ];
          }
        }
      );</code></pre><pre><code class="whhtml">    &lt;/script&gt;
  &lt;/head&gt;
  &lt;body&gt;
  &lt;/body&gt;
&lt;/html&gt;
</code></pre>
    </div>

    <div class="section">
      <h2><a name="examples">Examples</a></h2>
      <dl>
        <dt><a href="benchmarker_creator.html">Benchmark Creator</a></dt>
        <dd>basic Benchmarker demo</dd>

        <dt><a href="benchmark_t_split-fancy.html">String#split</a></dt>
        <dd>using the <var>setup</var> code block</dd>

        <dt><a href="benchmark_t_camelize.html">String#camelize</a></dt>
        <dd>using <var>methods</var> generator</dd>

        <dt><a href="benchmark_t_loops.html">loops</a></dt>
        <dd>using <var>methodSets</var> generator</dd>

        <dt><a href="benchmark_t_domquery.html">DOM query</a></dt>
        <dd>Benchmarker options show-off ;-)</dd>

        <dt><em>Gallery</em>:</dt>
        <dd>
          (various Benchmarks, useful - to us - at some point in time)
          <ul>
            <li><a href="benchmark_t_looping.html">looping</a></li>
            <li><a href="benchmark_t_strip.html">String#strip</a></li>
            <li><a href="benchmark_t_repeat.html">String#repeat</a></li>
            <li><a href="benchmark_t_isin.html">AIs In?</a></li>
            <li><a href="benchmark_t_createOneElement.html">Create <var>One</var> <acronym>DOM</acronym> element</a></li>
            <li><a href="benchmark_t_createNElements.html">Create <var>N</var> <acronym>DOM</acronym> elements</a></li>
            <li><a href="benchmark_t_array-filling.html">Populating arrays</a></li>
          </ul>
        </dd>
      </dl>
    </div>

    <div class="section">
      <h2><a name="description">Description</a></h2>
      <p>
        This gadget's goal is to be an <em>easy-to-deploy</em> helper for
        JavaScript <a href="benchmark.html">Benchmark</a>s.
      </p>
      <p>
        <kbd>Benchmarker</kbd> modifies some default <kbd>Benchmark</kbd> options:
      </p>
      <ul>
        <li><kbd>responders</kbd>: <var>'HTMLish'</var> (sweeter results output)</li>
        <li><kbd>iterations</kbd>: <var>-0.5</var> (half a second sounds better)</li>
        <li><kbd>cooldown</kbd>: <var>50</var> (run with shorter delays)</li>
      </ul>

      <h3><a name="groups">Groups</a></h3>
      <p>
        <kbd>Benchmarker</kbd> can create multiple <kbd>Benchmark</kbd> objects.
        Each such object will be used for benchmarking a <em>group</em> of functions.
      </p>
      <p>
        All methods added through the meanings of the interactive "add method"
        gadget will be added to the group named <var>"default"</var>.
      </p>
      <p>
        In order to create additional groups, for the moment you will have to use
        the <a href="#option-setup">setup block</a> in order to populate
        the <a href="#methodSets"><var>methodSets</var> array</a>.
      </p>

      <h3><a name="methodSets">methodSets</a></h3>
      <p>
        This is a special "global" variable used to generate
        <a href="#groups">Benchmarker groups</a>.
        It's structure should look like this:
      </p>
<pre><code class="whjs">
set1 = {
  name: 'Methods Set Name',
  methods: { // functions to be benchmarked
    // name: code
      'ack': function() { return true; },
      'nak': function() { return false; },
  }
};
methodSets = [ set1, set2, set3, set4 ... ];
</code></pre>

      <h3><a name="wip">Work in Progress</a></h3>
      <p>
        <acronym title="As Far As I Can Tell">AFAICT</acronym>, this module
        will <em>always</em> be in a <em>work in progress</em> status.
      </p>
      <p>
        Check <a href="#todo">the ToDo</a> section for more info.
      </p>
    </div>

    <div class="section">
      <h2><a name="options">Options</a></h2>
      <p>No option is compulsory. The currently used options are:</p>
      <dl>
        <dt>
          <a name="option-scripts">scripts</a>
          <kbd>{Array}</kbd>
          <samp>[<code class="whjs">[]</code>]</samp>
        </dt>
        <dd>load this list of <var>scripts</var></dd>

        <dt>
          <a name="option-css">css</a>
          <kbd>{Array}</kbd>
          <samp>[<code class="whjs">[]</code>]</samp>
        </dt>
        <dd>load this list of <var>stylesheets</var></dd>

        <dt>
          <a name="option-summary">summary</a>
          <kbd>{String}</kbd>
          <samp>[<code class="whjs">''</code>]</samp>
        </dt>
        <dd>brief benchmark description</dd>

        <dt>
          <a name="option-description">description</a>
          <kbd>{String}</kbd>
          <samp>[<code class="whjs">''</code>]</samp>
        </dt>
        <dd>benchmark description</dd>

        <dt><a name="option-edit">edit</a>  <kbd>{Boolean}</kbd> <samp>[<code class="whjs">false</code>]</samp></dt>
        <dd>expand benchmark editor on page load</dd>

        <dt><a name="option-editOptions">editOptions</a>  <kbd>{Boolean}</kbd> <samp>[<code class="whjs">true</code>]</samp></dt>
        <dd>expand benchmark options when editing</dd>

        <dt><a name="option-editHandlers">editHandlers</a>  <kbd>{Boolean}</kbd> <samp>[<code class="whjs">false</code>]</samp></dt>
        <dd>expand benchmark handlers when editing</dd>

        <dt><a name="option-parallel">parallel</a>  <kbd>{Boolean}</kbd> <samp>[<code class="whjs">false</code>]</samp></dt>
        <dd>run multiple benchmarks in "parallel"</dd>

        <dt><a name="option-setup">setup</a>  <kbd>{Function}</kbd> <samp>[<code class="whjs">function(){}</code>]</samp></dt>
        <dd>
          This block is evaluated in "global" context, <em>before</em>
          any Benchmark object is even created (when you click <var>"run benchmark"</var>)
          <p>These "global" variables have a special meaning:</p>
          <ul>
            <li><kbd>methods</kbd> // <kbd>{Object}</kbd> <samp>[{}]</samp>
              - use it to programmatically populate Benchmark's <var>methods</var> parameter
              (they are added to the <a href="#groups">group</a> named "auto");
            </li>
            <li><kbd>methodSets</kbd> // <kbd>{Array}</kbd> <samp>[[]]</samp>
              - use it to programatically create multiple <a href="#groups">method groups</a>.
            </li>
          </ul>
        </dd>
      </dl>
    </div>

    <div class="section">
      <h2><a name="dependencies">Dependencies</a></h2>
      <ul>
        <li><a href="http://www.prototypejs.org/">Prototype</a></li>
        <li><a href="http://script.aculo.us/">script.aculo.us</a> (effects.js and controls.js)</li>
        <li><span class="fixme">neodom</span> (Prototype tweaks, ElasticInput, ElasticTextarea)</li>
        <li><span class="fixme">Message</span> (notifications)</li>
        <li><span class="fixme">Loading</span> (XHR notifications)</li>
      </ul>
    </div>

    <div class="section">
      <h2><a name="incompatibilities">Incompatibilities</a></h2>
      <p>None reported.</p>
    </div>

    <div class="section">
      <h2><a name="bugs">Bugs and Limitations</a></h2>
      <p>No bugs have been reported.</p>
    </div>

    <div class="section">
      <h2><a name="todo">To Do</a></h2>
      <ul>
        <li>allow modifying *all* Benchmarker parameters — brr, UI crap</li>
        <li>allow modifying responders parameters — weirdo!</li>
        <li>permit testing functions check (individual run) — could be useful</li>
        <li>benchmarking web service  — hehe, web2.0 nerds, far in the future... *maybe*</li>
        <li>... checking <a href="benchmark.html#todo">Benchmark's ToDo section</a> should be fun too ;-)</li>
      </ul>
    </div>

    <div class="section">
      <h2><a name="see-also">See Also</a></h2>
      <ul>
        <li><a href="benchmark.html">Benchmark</a></li>
        <li><a href="benchmark_htmlish.html">Benchmark.Responders.HTMLish</a></li>
      </ul>
    </div>

    <div class="section">
      <h2><a name="credits">Credits</a></h2>
      <p>There are way too many to be credited here as I used
      lots of sources of inspiration for baking these toys.</p>
      <ul>
        <li><a href="http://www.crockford.com/">Douglas Crockford</a></li>
        <li><a href="http://dean.edwards.name/">Dean Edwards</a></li>
        <li><a href="http://www.quirksmode.org/">Peter-Paul Koch</a></li>
        <li><a href="http://mihai.bazon.net/">Mihai Bazon</a></li>
        <li><a href="http://www.alistapart.com/">A List Apart</a></li>
        <li><a href="http://www.prototypejs.org/">Prototype</a> (<a href="http://conio.net/">Sam Stephenson</a>)</li>
        <li><a href="http://script.aculo.us/">script.aculo.us</a> (<a href="http://mir.aculo.us/">Thomas Fuchs</a>)</li>
        <li><a href="http://www.jquery.com/">jQuery</a> (<a href="http://ejohn.org/">John Resig</a>)</li>
        <li><a href="http://www.mochikit.com/">MochiKit</a> (Bob Ippolito)</li>
      </ul>
      <p>Thank you all and my apologies for those missing from this enumeration.</p>
    </div>

    <div class="section">
      <h2><a name="authors">Authors</a></h2>
      <p>
        <a href="http://www.altblue.com/">Marius Feraru</a>,
        &lt;<a href="mailto:altblue@n0i.net">altblue@n0i.net</a>&gt;.
      </p>
    </div>

    <div class="section">
      <h2><a name="license">License and Copyright</a></h2>
      <p>
        &copy; 2006-2007 Marius Feraru &lt;altblue@n0i.net&gt;.
        All rights reserved.
      </p>
      <p>
        This module is free software; you can redistribute it
        and/or modify it under the same terms as Perl itself.
      </p>
    </div>

    <div class="section">
      <h2><a name="disclaimer">Disclaimer of Warranty</a></h2>
      <p>
        Because this software is licensed free of charge, there is no warranty
        for the software, to the extent permitted by applicable law. Except when
        otherwise stated in writing the copyright holders and/or other parties
        provide the software "as is" without warranty of any kind, either
        expressed or implied, including, but not limited to, the implied
        warranties of merchantability and fitness for a particular purpose.
        The entire risk as to the quality and performance of the software is
        with you. should the software prove defective, you assume the cost
        of all necessary servicing, repair, or correction.
      </p>
      <p>
        In no event unless required by applicable law or agreed to in writing
        will any copyright holder, or any other party who may modify and/or
        redistribute the software as permitted by the above license, be liable
        to you for damages, including any general, special, incidental,
        or consequential damages arising out of the use or inability to use
        the software (including but not limited to loss of data or data being
        rendered inaccurate or losses sustained by you or third parties or a
        failure of the software to operate with any other software), even if
        such holder or other party has been advised of the possibility of such
        damages.
      </p>
    </div>

    <script type="text/javascript">
      var hl = new Highlighter(false); hl.init();
      new Tree($('toc'));
      document.getElementById('version-revision').innerHTML = Benchmarker.toString();
    </script>
  </body>
</html>
